// Copyright (c) MatrixFramework. All rights reserved.
// Licensed under the MIT License. See LICENSE in the project root for license information.

using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using MatrixFramework.Core.Results;
using MatrixFramework.Keycloak.Abstractions.Models;
using MatrixFramework.Keycloak.Abstractions.Options;

namespace MatrixFramework.Keycloak.Abstractions.Services;

/// <summary>
/// MatrixFramework统一Keycloak管理服务接口
/// </summary>
public interface IKeycloakAdminService
{
    /// <summary>
    /// 获取配置选项
    /// </summary>
    KeycloakOptions Options { get; }

    // ==================== Realm管理 ====================

    /// <summary>
    /// 创建Realm
    /// </summary>
    /// <param name="realmInfo">Realm创建信息</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>Realm创建结果</returns>
    Task<Result<RealmCreationResult>> CreateRealmAsync(RealmCreationInfo realmInfo, CancellationToken cancellationToken = default);

    /// <summary>
    /// 删除Realm
    /// </summary>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>操作结果</returns>
    Task<Result> DeleteRealmAsync(string realmName, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取Realm信息
    /// </summary>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>Realm信息</returns>
    Task<Result<RealmInfo>> GetRealmAsync(string realmName, CancellationToken cancellationToken = default);

    /// <summary>
    /// 更新Realm配置
    /// </summary>
    /// <param name="realmName">Realm名称</param>
    /// <param name="configuration">配置信息</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>操作结果</returns>
    Task<Result> UpdateRealmAsync(string realmName, RealmConfiguration configuration, CancellationToken cancellationToken = default);

    /// <summary>
    /// 测试Realm连接
    /// </summary>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>连接测试结果</returns>
    Task<Result<bool>> TestRealmConnectionAsync(string realmName, CancellationToken cancellationToken = default);

    // ==================== 用户管理 ====================

    /// <summary>
    /// 创建用户
    /// </summary>
    /// <param name="userInfo">用户信息</param>
    /// <param name="realmName">Realm名称，为空则使用默认Realm</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>用户创建结果</returns>
    Task<Result<UserCreationResult>> CreateUserAsync(UserCreationInfo userInfo, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 更新用户信息
    /// </summary>
    /// <param name="userId">用户ID</param>
    /// <param name="userInfo">用户信息</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>操作结果</returns>
    Task<Result> UpdateUserAsync(string userId, UserUpdateInfo userInfo, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 删除用户
    /// </summary>
    /// <param name="userId">用户ID</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>操作结果</returns>
    Task<Result> DeleteUserAsync(string userId, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取用户信息
    /// </summary>
    /// <param name="userId">用户ID</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>用户信息</returns>
    Task<Result<UserInfo>> GetUserAsync(string userId, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 根据用户名获取用户
    /// </summary>
    /// <param name="username">用户名</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>用户信息</returns>
    Task<Result<UserInfo?>> GetUserByUsernameAsync(string username, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 搜索用户
    /// </summary>
    /// <param name="searchRequest">搜索请求</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>用户搜索结果</returns>
    Task<Result<PagedSearchResult<UserInfo>>> SearchUsersAsync(UserSearchRequest searchRequest, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取用户列表（搜索用户的别名方法）
    /// </summary>
    /// <param name="searchRequest">搜索请求</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>用户搜索结果</returns>
    Task<Result<PagedSearchResult<UserInfo>>> GetUsersAsync(UserSearchRequest searchRequest, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 重置用户密码
    /// </summary>
    /// <param name="userId">用户ID</param>
    /// <param name="newPassword">新密码</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>操作结果</returns>
    Task<Result> ResetPasswordAsync(string userId, string newPassword, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 启用/禁用用户
    /// </summary>
    /// <param name="userId">用户ID</param>
    /// <param name="enabled">是否启用</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>操作结果</returns>
    Task<Result> SetUserEnabledAsync(string userId, bool enabled, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取用户角色
    /// </summary>
    /// <param name="userId">用户ID</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>用户角色列表</returns>
    Task<Result<List<string>>> GetUserRolesAsync(string userId, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 为用户分配角色
    /// </summary>
    /// <param name="userId">用户ID</param>
    /// <param name="roles">角色列表</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>操作结果</returns>
    Task<Result> AssignRolesToUserAsync(string userId, List<string> roles, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 从用户移除角色
    /// </summary>
    /// <param name="userId">用户ID</param>
    /// <param name="roles">角色列表</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>操作结果</returns>
    Task<Result> RemoveRolesFromUserAsync(string userId, List<string> roles, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取用户组
    /// </summary>
    /// <param name="userId">用户ID</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>用户组列表</returns>
    Task<Result<List<string>>> GetUserGroupsAsync(string userId, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 将用户添加到组
    /// </summary>
    /// <param name="userId">用户ID</param>
    /// <param name="groupId">组ID</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>操作结果</returns>
    Task<Result> AddUserToGroupAsync(string userId, string groupId, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 将用户从组中移除
    /// </summary>
    /// <param name="userId">用户ID</param>
    /// <param name="groupId">组ID</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>操作结果</returns>
    Task<Result> RemoveUserFromGroupAsync(string userId, string groupId, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取用户会话列表
    /// </summary>
    /// <param name="userId">用户ID</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>用户会话列表</returns>
    Task<Result<List<UserSessionInfo>>> GetUserSessionsAsync(string userId, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 注销用户所有会话
    /// </summary>
    /// <param name="userId">用户ID</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>操作结果</returns>
    Task<Result> LogoutUserAsync(string userId, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 验证用户凭据
    /// </summary>
    /// <param name="username">用户名</param>
    /// <param name="password">密码</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>验证结果</returns>
    Task<Result<bool>> ValidateUserCredentialsAsync(string username, string password, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取用户权限
    /// </summary>
    /// <param name="userId">用户ID</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>用户权限列表</returns>
    Task<Result<List<string>>> GetUserPermissionsAsync(string userId, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 批量导入用户
    /// </summary>
    /// <param name="users">用户列表</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>导入结果</returns>
    Task<Result<UserImportResult>> ImportUsersAsync(List<UserCreationInfo> users, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 导出用户
    /// </summary>
    /// <param name="searchRequest">搜索条件</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>导出结果</returns>
    Task<Result<UserExportResult>> ExportUsersAsync(UserSearchRequest searchRequest, string? realmName = null, CancellationToken cancellationToken = default);

    // ==================== 角色管理 ====================

    /// <summary>
    /// 创建角色
    /// </summary>
    /// <param name="roleInfo">角色信息</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>角色创建结果</returns>
    Task<Result<RoleCreationResult>> CreateRoleAsync(RoleCreationInfo roleInfo, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 删除角色
    /// </summary>
    /// <param name="roleName">角色名称</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>操作结果</returns>
    Task<Result> DeleteRoleAsync(string roleName, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取角色列表
    /// </summary>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>角色列表</returns>
    Task<Result<List<RoleInfo>>> GetRolesAsync(string? realmName = null, CancellationToken cancellationToken = default);

  
    // ==================== 客户端管理 ====================

    /// <summary>
    /// 创建客户端
    /// </summary>
    /// <param name="clientInfo">客户端信息</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>客户端创建结果</returns>
    Task<Result<ClientCreationResult>> CreateClientAsync(ClientCreationInfo clientInfo, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取客户端信息
    /// </summary>
    /// <param name="clientId">客户端ID</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>客户端信息</returns>
    Task<Result<ClientInfo>> GetClientAsync(string clientId, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取客户端列表
    /// </summary>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>客户端列表</returns>
    Task<Result<List<ClientInfo>>> GetClientsAsync(string? realmName = null, CancellationToken cancellationToken = default);

    // ==================== 权限作用域管理 ====================

    /// <summary>
    /// 创建权限作用域
    /// </summary>
    /// <param name="scopeInfo">权限作用域信息</param>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>权限作用域创建结果</returns>
    Task<Result<ScopeCreationResult>> CreateScopeAsync(ScopeCreationInfo scopeInfo, string? realmName = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取权限作用域列表
    /// </summary>
    /// <param name="realmName">Realm名称</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>权限作用域列表</returns>
    Task<Result<List<ScopeInfo>>> GetScopesAsync(string? realmName = null, CancellationToken cancellationToken = default);

    // ==================== 多租户管理 ====================

    /// <summary>
    /// 同步租户到Keycloak
    /// </summary>
    /// <param name="tenantInfo">租户信息</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>同步结果</returns>
    Task<Result<TenantSyncResult>> SyncTenantAsync(TenantInfo tenantInfo, CancellationToken cancellationToken = default);

    /// <summary>
    /// 批量同步租户
    /// </summary>
    /// <param name="tenantInfos">租户信息列表</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>批量同步结果</returns>
    Task<Result<BatchTenantSyncResult>> SyncTenantsAsync(List<TenantInfo> tenantInfos, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取租户同步状态
    /// </summary>
    /// <param name="tenantId">租户ID</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>同步状态</returns>
    Task<Result<TenantSyncStatus>> GetTenantSyncStatusAsync(string tenantId, CancellationToken cancellationToken = default);

    // ==================== 健康检查 ====================

    /// <summary>
    /// 测试连接
    /// </summary>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>连接测试结果</returns>
    Task<Result<bool>> TestConnectionAsync(CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取服务器信息
    /// </summary>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>服务器信息</returns>
    Task<Result<ServerInfo>> GetServerInfoAsync(CancellationToken cancellationToken = default);

    /// <summary>
    /// 健康检查
    /// </summary>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>健康检查结果</returns>
    Task<Result<HealthCheckResult>> HealthCheckAsync(CancellationToken cancellationToken = default);
}